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1.0 General Notes 



DATATRIEVE-ll Version 2.0 is a major extension to DATATRIEVE 
Version 1. Improvements, largely based by user feedback, have been made to 
many areas including ease of use, data integrity, raw functionality, and data 
subsystems supported. 

The software requirements for DATATRIEVE-ll Version 2.0 include 
RMS-11K Version 1.8. The following versions of the various operating sys- 
tems are required: 

RSX-11M V3.2 

RSTS/E V7.0 (with monitor RSX emulation) 
IAS V3.0 (with "T" kit installed) 
RSX-llM-Plus V1.0 
VMS V2.0 

The DATATRIEVE installation procedure will verify that the proper version 
of RMS-11K is installed. 

1.1 New Features 

DATATRIEVE-ll Version 2.0 is particularly rich in new features. A partial 
listing follows. 

1. A major new subsystem, the Application Design Tool (ADT), has been 
added. ADT allows less experienced users to set up simple DATATRIEVE 
applications. Through a simple dialog, ADT generates a DATATRIEVE 
command file containing the record, domain, and file definitions. 

2. Support for data hierarchies. Use of hierarchies allows manipulation of 
complex data containing lists. A hierarchy may be defined as a single file 
with a repeating group or multiple domains automatically cross linked. 
Extensions related to hierarchies include the inner print list and the ANY 
Boolean expression, which allows DATATRIEVE to search a list for the 
existence of a particular record. 

3. Support for the COBOL OCCURS clause. Use of the OCCURS clause 
permits definition of records containing a repeating group (list). The list 
may be of fixed or variable length. 

4. Support for views. A new type of domain has been added to describe 
artificial views of one or more elementary (i.e. non-view) domains. Views 
can be used to restrict the set of fields accessible, to apply an automatic 
selection criterion to a file, or to cross link a number of elementary 
domains to form an apparent hierarchy. Once defined, a view is indistin- 
quishable from an RMS domain to the user. 

5. A DATE data type has been added to DATATRIEVE. This allows easy 
inclusion of dates in DATATRIEVE records, direct comparison of dates, 
and computation of elapsed days. Dates may be formatted for printing in 
virtually any form. Similarly, DATATRIEVE accepts the entry of dates in 
virtually any form. The DATATRIEVE date format is compatible with 
the VMS date standard. 
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6. Table support. Tables are generally used to translate encoded values 
into something that can be printed, but they can have other uses. 
DATATRIEVE tables are stored in the data dictionary and can be edited 
by the DATATRIEVE editor. Table lookups are performed by the VIA 
value expression; table searches (for table membership) are specificied 
with the Boolean IN expression. 

7. Automatic value validation. A Boolean validation expression may be in- 
cluded as part of a field description in a record definition. If specified on a 
field, the validation expression is automatically executed every time the 
field is modified to insure that only legal values are stored in a data base. 
If a validation error is detected, the user is re-prompted for a new value if 
possible, or the DATATRIEVE statement is aborted. 

8. Re-prompting. If a validation error, conversion error, or truncation error is 
detected during an assignment, STORE, or MODIFY, DATATRIEVE 
automatically re-prompts the user for a new value. This vastly improves 
DATATRIEVE's usefulness as a data entry tool. 

9. COMPUTED BY fields. A field in a record definition may be defined as a 
COMPUTED BY field by specifying a value expression to be computed for 
its value. A COMPUTED BY field takes no space in the actual RMS 
record, and is computed on reference. A COMPUTED BY field may be 
used in conjunction with a table to provide completely automatic table 
lookup. 

10. Dictionary EXTRACT command. A new command, EXTRACT, has been 
provided to copy domain definitions, record definitions, procedures, and 
tables from the DATATRIEVE data dictionary to an external file. The file 
produced by EXTRACT is in a form such that it can be used as a com- 
mand file. 

11. SHOW FIELDS. A new SHOW option, SHOW FIELDS, has been added 
to print field names and data types for all fields in ready domains. 

12. A DEFINE DICTIONARY command has been added to create a private 
dictionary. 

13. A new SUM statement has been added. The SUM statement allows very 
simple computation of totals and sub-totals on collections. 

14. Both global and local variables are supported. Variables may be 
DECLAREd at DATATRIEVE command level or within BEGIN-END 
blocks. The former are considered global variables and the later local 
variables. Global variables are preserved from DATATRIEVE statement 
to statement. 

15. A second form of concatenation (expressed as !!) is provided to guarantee 
that no blanks are included between the two components. 

16. A new report writer formatter has been implemented. The new formatter 
is better at column alignment, and is much better at wrapping report 
lines. 
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17. The DATATRIEVE divide algorithm has been improved to guarantee the 
same precision internally as is required for the result (taken from the 
context of the divide operation). As a consequence, it is no longer neces- 
sary to multiply sub-expressions by 1.0, 1.000, etc., to get a significant 
result. 

18. The access control for record, procedure, and table definitions in the data 
dictionary has been enhanced. In DATATRIEVE V2, R (read) access is 
required to SHOW or EXTRACT a record, procedure, or table definition. 
In order to access an object, the privilege E (execute) is required. This 
permits a user to execute but not see a procedure or table. 

19. D ATATRIEVE-1 1 Version 2.0 recovers from RMS bucket locked errors 
under most circumstances. When DATATRIEVE encounters a locked 
bucket, it goes into a wait loop until the bucket is unlocked or about 15 
seconds elapse. 

20. A new edit-string character has been included called the Text edit charac- 
ter (T format). T format allows a field containing a group of text to be 
printed with regard to space or tab seperators between words. Although it 
does not right justify, it allows a reasonable way to print otherwise hard to 
print text. 

21. An edit-string character to allow insertion of a hyphen (-) while printing 
an alphanumeric field (defined with PIC X) has been added. 

22. A SHOW SPACE command has been added to show the use of the central 
storage pool and help you avoid the "out of space" problem. 

23. The last entry of a password table may no longer be deleted. If the last 
entry that has C (control) access has been deleted, you may access the 
password table from a [l,n] account. 

1.2 Restrictions Removed 

A number of the arbitrary restrictions of DATATRIEVE Version 1.1 have 
been lifted. This is not to say that DATATRIEVE Version 2 does not have 
limitations, but just that most numerical restrictions have been eliminated. 
When the central storage pool is exhausted, it is exhausted. The restrictions 
removed are: 

1. Collections are no longer restricted to 5,000 records. 

2. The maximum number of TOTALs in the report writer is no longer 16. 

3. The maximum number of fields in a group item is much greater than 123 
(but still not infinite!). 

4. Multiplication and division are supported up to 18 full decimal digits. 

5. Scale factors are now supported on floating point numbers (COMP-1 and 
COMP-2). 
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1.3 Incompatibilities 

When a change to the DATATRIEVE language is required, both the new and 
old ways of doing an operation will be supported whenever possible for one full 
release (one year minimum). After a full release, the old way may not be 
supported. 

The known incompatibilities between Version 1.1 and Version 2.0 are: 

1 . Reports are terminated in Version 1. 1 by the statement "REPORT END" . 
The proper way to terminate a report specification in Version 2 
is "END-REPORT". Both will be supported for the life of 
D ATATRIEVE-1 1 Version 2. 

2. The report options NO-DATE and NO-NUMBER should be given as 
"NO DATE" and "NO NUMBER". Both forms will be supported for the 
life of Version 2. 

3. DATATRIEVE Version 1 contained a bug which allocated a three word 
binary data type for a COMP field between 10 and 14 digits long. The 
correct length for this range is 4 words. As a consequence, DATATRIEVE 
Version 2.0 cannot read files it created which contain COMPs of the above 
range (this does NOT apply to COMP-1, COMP-2, COMP-3, COMP-5, 
or COMP-6). These files must be restructured by DATATRIEVE Version 
1.1 to fields of decimal length 15 or greater. (Note: COBOL can not read 
these files either.) 

4. The report formatter for Version 2 is different from the one used for 
Version 1. 

5. The size of the maximum input string from the terminal has been reduced 
from 255 to 132 characters. This means that the number of continuation 
lines permitted may decrease, since continuation lines are considered as 
part of one input string. 

6. The word BYE that was printed on the terminal at the end of a 
DATATRIEVE session has been deleted. 

7. The number of records found by the FIND statement is not printed if the 
find statement is embedded in a procedure. If the FIND statement is 
entered directly, is contained in a command file, or is the last statement in 
a procedure, the count is printed. 

8. The precedence of statistical functions has changed. Consider, for exam- 
ple, the value expression: 

TOTAL SALARY + COMMISSION 

In Version 1 of DATATRIEVE, this was parsed as: 

TOTAL (SALARY + COMMISSION) 

which was usually okay. This, unfortunately, caused the expression 

TOTAL SALARY + TOTAL COMMISSION 
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to be parsed: 

TOTAL (SALARY + (TOTAL COMMISSION)) 

which would have been wrong had DATATRIEVE executed it (resulting 
in the familiar ARVLCP: Expected value block message). 

In Version 2 of DATATRIEVE, the statistical function is the high preced- 
ence operator; to take the total, average, max, or min of an expression it is 
necessary to put the expression in parentheses. Continuing with our exam- 
ple, the correct form of the expression is: 

TOTAL (SALARY + COMMISSION) 

9. Since floating point numbers now have scaling, any COMP-1 or COMP-2 
field which had a PIC clause containing a decimal position will now be 
believed (before it was ignored). It will be necessary to fix the PICTURE 
and your data will be treated as it was in Version 1.1. 

10. One of the persistent problems of DATATRIEVE has been the frequency 
with which the infamous central storage pool is exhausted. DATATRIEVE 
Version 2 may or may not be better than 1.1 in this respect depending on 
exact application and operating system. It is difficult to compare the 
relative sizes of the work space available to DATATRIEVE Version 2 and 
earlier versions. The changes that affect pool space are: 

1. The code portion of DATATRIEVE Version 2.0 is about five K bytes 
larger than Version 1.1 with a corresponding reduction in pool space. 

2. The maximum task size on RSTS/E has been increased to about 62K 
bytes, making 7K bytes additional pool space available. 

3. The amount of RMS buffer space required for indexed files has been 
drastically reduced for Version 2. As a result from one half to 2K bytes 
of additional space per indexed file become available for other usage. 

4. All internal DATATRIEVE blocks (the heaviest user of pool space 
after RMS buffers) are at least two bytes longer. 

In summation, RSTS/E and VMS users have more space; RSX and IAS users 
may have more or less. 

1 .4 Restrictions and Limitations 

The following restrictions and limitations apply to DATATRIEVE-11 Version 
2.0: 

1. On VMS the following sequence will cause DATATRIEVE to abort with a 
severe error: 

$MCR 

MCR> DTR 
DTR> -Z 
MCR> DTR 
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2. The DATATRIEVE Editor does not prohibit the deletion of the last entry 
in a table. If a table is edited and has no code and description pairs, any 
subsequent reference will result in the error message: 



( LK ) LXFRT V : retrieval segment not found 

3. At least one space must be specified following the edit-string of a USING 
clause in a print-list. If a space is not specified and the character following 
the comma is a valid edit-string character (such as a T in TOTAL), the 
statement will not be executed and the "Expected x encountered y" mes- 
sage will be printed. 
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2.0 Installation Notes 



2.1 DATATRIEVE Customization 

There are a number of DATATRIEVE options which may be set at installa- 
tion time. Many of these are now for Version 2.0. All are changed by editing 
the file QD.MAC before execution of the DATATRIEVE installation com- 
mand or build file. The options are: 

1. The name and location of the DATATRIEVE message file. The default 
name is LB:[1,2]QUERY.MSG; for RSTS/E, the default name is 
LB:QUERY.MSG. If some other device or account is to be used, the name 
should be changed. The message file name is referenced both by QDICT, 
which creates the message file at installation time, and DATATRIEVE 
itself. 

2. The name and location of the DATATRIEVE data dictionary. The default 
name is LB:[1,2]QUERY.DIC; for RSTS/E, the default name is 
LB:QUERY.DIC. If, for some reason, it is important to move the diction- 
ary to some other device or account, the file name can be changed. 

3. Whether or not DATATRIEVE is to give a warning message when a 
shorter than expected RMS record is read. 

4. Whether line printer spooling is to be enabled (RSX-11M only). 

5. The action to be taken for divide by zero. The two options available are: 
Give a warning message and return -1, and quietly return the value 0. 

6. The guide mode terminal type. This is only necessary for RSX-11M with 
the old terminal handler, and only with VTlOOs transmitting at a baud 
rate greater than 1200. In short, this option should never be necessary. 

7. The default protection for dictionary objects. Version 1.1 generated a pro- 
tection element giving all privileges to the creator of a dictionary object 
only. In Version 2.0, there are three choices: All privileges can be given to 
the creator's group (default), all privileges to just the creator (compatible 
with Version 1), and all privileges to the entire world. 

8. Whether or not the Application Design Tool (ADT) is to be enabled or 
disabled. 

9. The default setting for columns-page. In Version 2.0, the default is set to 
80. In Version 1.1, the default was 132. 

Specific instructions for each option are contained in QD.MAC itself. 

2.2 Installation Clean-Up 

The installation procedure does not automatically delete files from the instal- 
lation account (except VMS) even though they may no longer be needed or 
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rarely needed. There are two groups of files: those only needed for installation, 
and those required for future patching, but not needed for day to day use of 
DATATRIEVE. 

To help you clean up the installation account, command files are included to 
delete these now unnecessary files. Each group may be deleted independently 
of the other, or you may choose not to delete them at all. 

These command files are not included for VMS since the normal VMS instal- 
lation process deletes all files from the installation account. Specific details 
for the other operating systems follow. 

2.2.1 RSX-11M and RSX-1 1 M-PLUS Operating Systems — After a successful 
installation of DATATRIEVE, you may delete those files only necessary for 
installation by typing: 

> SDELRX 1 

The following files will be deleted: 

MSGS.SEQ 

DTR.TST 

QE11M.TKB 

QD11M.TKB 

QC11M.TKB 

QD.MAC 

DTR11M.CMD 

The files that are unnecessary for normal execution of DATATRIEVE, but are 
necessary for patching, may be deleted by typing: 

> @DELRX2 

The following files will be deleted: 

DTRLIB.OLB 

RELEASE.RNO 

DTR11M.TKB 

DTR11M.ODL 

RMSRSX.ODL 

2.2.2 RSTS/E Operating System — After a successful installation of 
DATATRIEVE, you may delete those files only necessary for installation by 
typing: 

RUN $PIP 

* @DELRSi ,CMD 
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The following files will be deleted: 



MSGSJ8EQ 

DTR.TST 

QD.MAC 

DTRSTS.CTL 

QDTSTS.TKB 

QERSTS.TKB 

QCRSTS.TKB 

The files that are unnecessary for normal execution of DATATRIEVE, but are 
necessary for patching may be deleted by typing: 

RUN $PIP.SAU 
* §DELRS2 ♦ CMD 



The following files will be deleted: 

DTR.ODL 

DTRLIB.OLB 

RELEASE,RNO 

DTRSTS.TKB 

DTRSTS.ODL 

RMSRST.ODL 

2.2.3 IAS Operating System — After a successful installation of 
DATATRIEVE, you may delete those files only necessary for installation by 
typing: 

PDS> SDELIA1.CMD 



The following files will be deleted: 

MSGS.SEQ 

DTR.TST 

QD.MAC 

DTRIAS.CMD 

QDIAS.LNK 

QCIAS.LNK 

QEIAS.LNK 

QEIAS.ODL 

QCIAS.ODL 

QDIAS.ODL 

The files that are unnecessary for normal execution of DATATRIEVE, but are 
necessary for patching may be deleted by typing: 

PDS> iDELIA2.CMD 
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The following files will be deleted: 



DTR.ODL 

DTRLIB.OLB 

RELEASE.RNO 

DTRIAS.LNK 

DTRIAS.ODL 

RMSRSX.ODL 
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3.0 Documentation Omissions and Changes 



The following items were omitted from the documentation or have been 
changed since the documentation was completed. 

1. The relational operator CONTAINING may be abbreviated as CONT. 

2. The User's Guide states that tables must be released explicitly by a 
RELEASE statement. This has been modified; if a global FINISH is 
specified (that is one which has no domains named), all tables currently 
loaded in the DATATRIEVE workspace will be released. If a specific 
domain is named to be FINISHed, no tables will be released and any 
tables associated with that domain must be explicitly released if you no 
longer need them. 

3. Section 2.3 of the Installation Guide (IAS Installation Procedures) incor- 
rectly specifies that files will be located in UIC [11,130], [111,130] and 
[311,130]. The UIC in all cases should be [SELF]. 

4. Section 3.3 of the Installation Guide (RSX Installation Procedures) incor- 
rectly specifies that files will be located in UIC [1,24] and [1,34]. The UIC 
in both cases is [SELF]. 

5. In Section 3.2 of the Installation Guide (RSX Installation Procedures) add 
after step: la. Ensure that a directory exists for the symbol <LIBUIC> 
that is used by indirect command files. 

6. Section 5.2.4 of the Installation Guide (VMS Installation Procedures) is 
incomplete. If you edit QD.MAC, additional questions will be asked re- 
garding the name and location of the dictionary and message file. 
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4.0 Known Problems 

The following bugs have been identified and will be fixed with patches pub- 
lished in the Software Dispatch: 

1. A floating point field (COMP-1 or COMP-2) with a value of prints as -0. 

2. The text format (EDIT-STRING T) will sometimes print an extra line 
after the text field is printed. 
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